1. Core Engine Lab

Goals

After completing this lab, you should understand the following Apache Camel key concepts:

  • Route

  • Processor

  • CamelContext

  • DSL

  • Message

  • Exchange

You should be familiar with JBoss Developer Studio and the Fuse Camel Editor.

Lab Assets

The lab exercises and solutions are available in the following zip archives:

1.1. Explore a Project

The goal of this exercise is to familiarize you with a typical integration project.

In this lab exercise, you will complete the following activities:

  • Use JBoss Developer Studio to create a new Fuse project.

  • View Apache Camel Routes.

  • Run a project locally.

  • Use the Palette within the Camel Editor to add a log processor.

1.1.1. Create a New Fuse Project

  1. Launch JBoss Developer Studio on your computer.

  2. Select another workspace ~/Temp/workspace-gpe-demo.

  3. Select File → New → Fuse Project.

    new fuse project
    Figure 1. JBoss Developer Studio - New Fuse Project

  4. Do not change the default project Location.

  5. Click Next.

    project location
    Figure 2. New Fuse Project - Select project location

  6. In the New Fuse Project — Select a project archetype to create and specify details window, select camel-archetype-activemq as the Apache Maven archetype.

    1. For the Artifact Id select demo1-camel.

    2. For the Version number, select 1.0.

    3. For the Package name, leave the default selection, com.mycompany.demo1.camel.

      select project archetype
      Figure 3. New Fuse Project - Select project archetype

  7. Click Finish.

1.1.2. View the Apache Camel Routes

This project contains two Apache Camel routes. The first route consumes three XML files from the src/data directory and creates an Exchange for every XML file. The Exchange contains the file metadata as headers and properties, and it publishes a JMS Message to the personal.records queue.

The second route consumes the JMS Message from the queue, and it creates an Exchange that is evaluated against a condition using a Content Base Router (CBR) Enterprise Integration Pattern (EIP). The CBR checks the JMS message and corresponding XML file to see if it contains the /person/city/ tag with a value equal to London. If the condition is matched, the Exchange creates a file with the contents of the JMS Message in the target/messages/uk directory. If the condition is not matched, the Exchange creates a file in the target/messages/others directory instead.

Follow these steps to view the Apache Camel Routes:

  1. On the menu, select Window → Open Perspective → Fuse Integration.

    open perspective fuse integration
    Figure 4. Open Perspective - Fuse Integration

  2. Use Project Explorer to open the demo1-camel project and verify that the contents of the project appear:

    • src/main/java

    • src/main/resources

  3. Expand the collapsed src/main/resources directory to reveal the spring subfolder.

  4. In the spring subfolder, double-click the camel-context.xml file. The Fuse Camel Editor appears displaying an Apache Camel route.

    camel ide window
    Figure 5. Camel IDE Window

  5. On the menu, select Routes, and then select a route to view, either Route: 1 or Route: 2.

    switch routes
    Figure 6. Select a route to view

  6. Explore the properties defined for an endpoint by selecting one in the Camel Editor view and reviewing the information in the Properties view:

    1. Select the endpoint activemq:personnel.records.

    2. Open the Properties view (if necessary) and inspect the endpoint URI, ID, and description.

    3. In the Properties view, click the Documentation tab to review documentation for the endpoint/component.

      documentation tab
      Figure 7. Documentation tab

    4. Review the information for the when processor: The expression is /person/city = 'London' and the language is xpath.

    5. Verify that the URI syntax of the activemq endpoint is activemq:personnel.records

    6. Click the Source tab of the Camel Editor to inspect the Camel routes in XML format.

      Both Java DSL and Camel Spring XML are supported languages for the source view.
      dsl syntax
      Figure 8. Sample XML file

Now you have seen what a typical Camel project looks like, and you have learned how to use the Camel Editor to view the Apache Camel Routes.

1.1.3. Run the Project Locally

A Fuse project is a collection of Camel Routes associated with a CamelContext. You start the Fuse project within JBoss Developer Studio. As explained in the course, whenever a Spring application context or XML module blueprint is created, the different beans declared within the camel-context.xml file are instantiated by Spring or OSGi Blueprint. This is how both the DefaultCamelContext and the RouteBuilder classes (containing the DSL based Route definitions) are created.

Follow these steps to run the project:

  1. Expand the folder src/main/resources to reveal the spring folder containing the file camel-context.xml.

  2. Right-click the camel-context.xml file and select Run as → Local Camel Context.

    run as
    Figure 9. Run Local Camel Context

    The Apache Camel Maven plug-in starts and the Maven console log shows that the CamelContext is created, routes are started, and endpoints are consumed.

    maven console
    Figure 10. Maven Console

  3. Right-click the target directory of Project Explorer and select Refresh.

    1. Inspect the contents of the subdirectories messages/uk or messages/others to see the XML files that were created.

      target directories
      Figure 11. Project Explorer - Target Directories

  4. To differentiate between what is running within the JVM and what was created, use the JMX layer and the JMX Navigator to discover the different MBeans objects which form both the CamelContext as well as the ActiveMQ broker:

    1. Select the JMX Navigator view.

    2. Expand the Local Processes tree.

    3. Click the green plus icon to add a new JMX Server connection.

      jmx connection
      Figure 12. JMX Server Connection

    4. In the Create a new JMX Connection dialog box, click Next.

    5. Click the Advanced tab and add the JMX Url: service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi

    6. Click Finish. The Camel and Broker JMX domains are now displayed with icons.

    7. Expand the JMX Server icon, and select the Camel domain.

    8. Click Window→Show View→Other, and then select Diagram view to view a graphical representation of the Camel routes.

    9. Switch to the Properties view to view the number and processing duration of the processed messages.

      jmx navigator
      Figure 13. Sample JMX Navigator

1.1.4. Enable Tracing

Tracing enables you to track the contents of the Exchange and the activity of the processors.

Follow these steps to enable tracing:

  1. If it is collapsed, expand the CamelContext Mbean within the JMX Navigator.

  2. Right-click camel-1 Mbean, and then select Start Tracing.

    enable tracing
    Figure 14. JMX Navigator - Start Tracing

  3. Refresh the camel-1.

  4. Inspect the new icon (same icon as before but with a green bug) that represents the CamelContext.

    tracer context
    Figure 15. JMX Navigator - Tracer Context

  5. To further test the tracing feature, create a new message and and use the Messages view and Properties view to review processing details:

    1. Use Project Explorer to expand src/data.

    2. Copy the contents of message3.xml and paste into a new file, message4.xml.

    3. Save the new file in the same directory.

      new message
      Figure 16. Sample - New Message

    4. Use Project Explorer to expand src/data.

    5. Copy the contents of message3.xml and paste into a new file message5.xml.

    6. Save the new file in another directory, such as src/test for example, to exclude message5.xml from polling.

    7. Drag the message and drop it onto the file endpoint in the JMX Navigator.

      drag n drop
      Figure 17. Sample - Add a File to an Endpoint

    8. Open the Properties view to inspect tabular information about the processed Exchanges, including:

      • Route ID

      • Processor ID

      • Exchanges Completed

      • Exchanges Failed

      • Mean Processing Time

      • Max Processing Time

      • Min Processing Time

      • Last Processing Time

    9. Open the Messages view to inspect information reported by the trace feature about the content of the Exchange, including body and headers.

      tracing result
      Figure 18. Sample - Tracing results

  6. Click the red square icon in the Console view to terminate the Maven process.

    terminate
    Figure 19. Console - Terminate a Maven process

You have enabled and tested the tracing feature.

1.1.5. Add a Log Processor

In this activity, you explore the Palette in the Camel Editor and add a Log Processor to the project. The Palette contains various endpoints and processors that you use to design an Apache Camel project. They are organized by topic:

  • Endpoints

  • Routing

  • Control Flow

  • Transformation

  • Miscellaneous

palette
Figure 20. Camel Editor - Palette

Follow these steps to add a log processor:

  1. From the Palette (right side of the Camel Editor view) select Log under the Components folder.

  2. Drag the Log endpoint and drop it onto Route 1.

    drag log endpoint
    Figure 21. Sample - Add a Log Endpoint

  3. Inspect the Log endpoint icon that appears on the Design view.

    endpoint added
    Figure 22. Sample - Endpoint Added

  4. In the Design view, remove the connection between the file:src/data endpoint and the activemq endpoint:

    1. Right-click the connection, and then select Remove.

    2. Connect file:src/data to log.

      To remove any endpoint, you must first delete all connections to or from it.

  5. In the Design view, add an arrow connecting the log endpoint to the activemq endpoint:

    1. Move your cursor over the endpoint and click the Create Connection icon that appears.

      arrow from log
      Figure 23. Sample - Connecting Log Endpoint to Activemq

  6. Edit the log endpoint to add a message File has been processed.

    arrow activemq log
    Figure 24. Sample - Activemq Log

  7. Review the message log.

    add message log
    Figure 25. Sample - Message Log

  8. Rearrange the icons neatly and save the modified camel-context.xml file.

    result
    Figure 26. Sample - Exercise Result with Icons

  9. Click Run as → Local Camel Context to run the project again.

  10. Verify that a message appears at least four times in the Maven console.

    console log
    Figure 27. Sample - Results in Maven Console

  11. In Project Explorer, right-click the demo1-camel project and then select Close project.

1.2. Design a New Project

The goal of this exercise is to design a new integration project and create an Apache Camel Route using the Camel Editor. To do this, you use an existing Maven project and add to it a Camel route, a HelloBean, and business logic that sends a message to the console.

1.2.1. Import the Maven Project if not yet done

  1. Open JBoss Developer Studio.

  2. Import the camel-labs-VERSION-NUMBER-excercise Apache Maven project:

    1. From the menu, Select File → Import.

    2. Click Maven → Existing Maven Projects.

      importing lab asset2
      Figure 28. Import Maven Projects window

    3. Click Finish.

  3. In Project Explorer, confirm that the camel-lab-2 project was imported.

    imported project
    Figure 29. Sample - Imported Project

  4. Review the project contents:

    • pom.xml

    • HelloBean class

1.2.2. Add the sayHello Method to the Bean

Before you design the Apache Camel Route, you must add a sayHello method to the body of the class HelloBean. This method will be used by the route. The method accepts an exchange as an input parameter and returns a String.

  1. Open the HelloBean class and add a sayHello method.

    	public String sayHello(Exchange exchange) {
		String body = (String)exchange.getIn().getBody();
		return "Hello world ! " + body;
	}
The return type and the object returned will be used by the Apache Camel engine to add a Body to the Exchange with the String object Hello world ! xxxx"

1.2.3. Design the Apache Camel Route

You use the Camel Editor to create a new route that triggers a timer event at a specified interval (every X seconds). To design the route, you will complete these tasks:

  • Create a new CamelContext.

  • Edit the Endpoint and SetBody properties.

  • Add a bean tag and Bean processor to the project.

  • Add a log processor to the project.

    1. Create a new CamelContext:

      1. Open the Fuse Integration perspective.

      2. In Project Explorer (left panel), expand the src/main/resources/OSGI-INF/blueprint folder.

      3. Right-click the blueprint folder to select it.

      4. Select New -> Camel XML File.

        new camel xml file
        Figure 30. Project Explorer - New Camel XML file

      5. For the Framework, select OSGi Blueprint, and then click Finish.

      6. Inspect the folder to confirm that a new camelContext.xml was added.

    2. Edit the Endpoint and SetBody properties:

      1. Double-click the camelContext.xml file you just created to open it in the Camel Editor.

        camel route blueprint
        Figure 31. Camel Route Blueprint

      2. From the Components section of the Palette, select the timer endpoint and drag it onto the project.

      3. For the Uri field, select this text to define the URI: timer://demo?delay=5000

        timer endpoint
        Figure 32. Timer Endpoint

      4. From the Transformation section of the Palette, select the SetBody processor and drag it onto the project.

      5. Edit the properties of this processor to add an expression and set the language:

        • Enter your name for the Expression.

        • For the Language, select simple.

          setbody processor
          Figure 33. SetBody Processor

    3. Add the bean tag and bean processor:

      1. Switch to the source of the Camel route to add the following <bean> tag. This is required to instantiate the singleton bean, when the Blueprint context is created.

        <?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
       xmlns:camel="http://camel.apache.org/schema/blueprint"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
       http://camel.apache.org/schema/blueprint http://camel.apache.org/schema/blueprint/camel-blueprint.xsd">

  <bean id="helloBean" class="com.redhat.gpe.training.camel.HelloBean"/>

      2. Return to the Design view.

      3. From the Components section of the Palette, select a Bean processor and drag it onto the project.

      4. Edit the properties of the Bean processor:

        • Enter sayHello for the Method.

        • Select helloBean for the the Bean Name.

          bean endpoint
          Figure 34. Bean Endpoint

    4. Add a log processor:

      1. From the Components section of the Palette, select a Log processor and drag it onto the project.

      2. Edit the properties of this Log processor to add a simple expression that extracts the contents of the Exchange body:

        • For the Message, enter ${body}.

          log endpoint
          Figure 35. Log Endpoint

      3. Connect the endpoints and processors.

        route blueprint
        Figure 36. Route Blueprint - Connect Objects

      4. Save the modified Camel route and verify the result of the XML DSL route generated:

        <?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
       xmlns:camel="http://camel.apache.org/schema/blueprint"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
       http://camel.apache.org/schema/blueprint http://camel.apache.org/schema/blueprint/camel-blueprint.xsd">

  <bean id="helloBean" class="com.redhat.gpe.training.camel.HelloBean"/>

  <camelContext trace="false" xmlns="http://camel.apache.org/schema/blueprint">
    <route>
        <from uri="timer://demo?delay=5000" id="timer-of-the-demo">
            <description/>
        </from>
        <setBody>
            <simple>Charles</simple>
        </setBody>
        <bean ref="helloBean" method="sayHello"/>
        <log message="${body}"/>
    </route>
</camelContext>

</blueprint>

1.2.4. Run the Project Locally

  1. Right-click the camel-context.xml file and select Run as → Local Camel Context.

  2. Verify that messages appear in the log.

    console result
    Figure 37. Sample - Log Messages

You have completed this lab.